home *** CD-ROM | disk | FTP | other *** search
/ Eagles Nest BBS 8 / Eagles_Nest_Mac_Collection_Disc_8.TOAST / Developer Tools⁄Additions / MacsbugBook / MacsBug Book Disk / Read Me / Read Me
Encoding:
Text File  |  1991-02-24  |  8.4 KB  |  216 lines  |  [TEXT/MPS ]
  1. Directory of Files on the MacsBug Book Disk
  2. -------------------------------------------
  3. Debugger Prefs sources            Folder        Contains the sources and tools to build the Debugger Prefs file
  4. Put in System Folder            Folder        Contains MacsBug files and the Programmer's Key INIT
  5. Sample Application Sources        Folder        Contains the sources to the sample applications
  6. Sample Applications                Folder        Contains the sample applications that go with some chapters in the book
  7. Utilities
  8.     Mr. Bus Error                Folder        An INIT that help detects uses of null pointers.  Can be placed in the System Folder
  9.     About Programmer's Key        File        Description of Programmer's Key INIT
  10.     MakeTemplates                File        An MPW script that will convert Pascal sources (usually INCLUDE files) into MacsBug Templates
  11. Read Me                            File        This file
  12.  
  13. __________________________________________________________________
  14.  
  15. The rest of this file describes additions and changes to the disk enclosed
  16. with the MacsBug book.
  17.  
  18.  
  19. MakeTemplates Tool
  20. ------------------
  21.  
  22. Included in the Utilties folder on the MacsBug book disk is an
  23. MPW script that will take Pascal include files (like those shipped
  24. with MPW) and turn the records and procedure parameters into
  25. MacsBug templates.  These can then be used for examining data structures
  26. and parameters on the stack.
  27.  
  28. To use the tool, place it in your MPW scripts folder and then give
  29. the command MakeTemplate followed by the file you want to create
  30. templates from.  For example, to make QuickDraw templates, you would
  31. say:
  32.  
  33.     MakeTemplates "{PInterfaces}"QuickDraw.p
  34.     
  35. When the script is done, you will have the source to the templates
  36. left on your worksheet.  These may be copied into the Prefs.r file
  37. in the Debugger Prefs sources folder.  If you then rebuild the Debugger 
  38. Prefs file, the templates will be available.  Or you can use the
  39. method for building templates with MPW described in Chapter 19.
  40.  
  41. You may want to place your prefs in a separate template resource so
  42. that they may easily be moved or removed as desired.
  43.  
  44. You can also convert your own header files to make debugging your 
  45. code easier.
  46.  
  47. __________________________________________________________________
  48.  
  49. BigEasy Application Shell
  50. -------------------------
  51.  
  52. BigEasy is an application shell that can be used wiht LightSpeed C or MPW. It was 
  53. originally written by David Van Brink.  We used it to create the various sample 
  54. applications on the disk.  To build the sample applications yourself, you will 
  55. have to copy the files from the BigEasy folder into the folder with the sample 
  56. application source.  This is the directory structure the LightSpeed C projects
  57. or the MPW makefile expects.
  58.  
  59. __________________________________________________________________
  60.  
  61. There have also been some updates to MacsBug since the book was
  62. submitted for printing.  The rest of this file is from Apple
  63. Computer describing those changes.  In addition to this file from
  64. Apple, there is a known bug in the parsing of multiple commands on
  65. one line.  To see the effect, try the command line of:
  66.     3;4
  67. and you will see that 3=$00000003 and also that 3=$00000004.  This bug is just 
  68. an output bug.  Internally MacsBug is fine.  MacsBug 6.2 also includes a double colon
  69. operator.  A single colon, :, specifies the start of the procedure the PC is in,
  70. and a double colon, ::, specifies the start of the procedure that was in effect 
  71. during the last IL command. Finally, even though the text below specifies that the 
  72. DCMDs can't be created with MPW 3.2, we supply a Prefs32.make file that does
  73. just that.
  74.  
  75. You may also notice some cosmetic differences between the listings in
  76. the book and those displayed by MacsBug 6.2.  These are the result of
  77. last minute changes to MacsBug and are detailed in the following section.
  78. __________________________________________________________________
  79.  
  80. MacsBug 6.2    1/25/91    © Apple Computer, Inc. 1981-91
  81.  
  82. You should use the “Debugger Prefs” included with this MacsBug.
  83. It contains macros, templates, dcmds, and the C++ name unmangler.
  84. You may add your own resources to “Debugger Prefs”,
  85. or remove some to decrease memory usage.
  86.  
  87. =================================================
  88.  
  89. New features since 6.1
  90.  
  91. MacsBug 6.2 supports the Macintosh Plus and all newer
  92. Macintosh models. These are the Macintosh Plus, SE, II, IIx,
  93. IIcx, SE30, Portable, IIci, IIfx, Classic, IIsi and LC.
  94.  
  95. MacsBug 6.2 works reliably with all Apple monitors and all
  96. third-party monitors if their slot ROM and driver software
  97. have been designed according to the guidelines presented
  98. in Designing Cards and Drivers for the Macintosh II and
  99. Macintosh SE, with and without 32 bit QuickDraw.
  100.  
  101. MacsBug 6.2 runs under A/UX 2.0.
  102.  
  103. Typing Command-D instead of Command-; with an international
  104. keyboard accesses the symbol list.
  105.  
  106. If the selected symbol in the scrollable list contains a
  107. C++ or Object Pascal class name, then pressing the tab key
  108. qualifies the list by that name.
  109.  
  110. MacsBug 6.2 displays the name of the current application,
  111. the memory management scheme (24 bit/32 bit) currently used,
  112. and whether you are running and have access to virtual memory.
  113.  
  114. New options for the Find command allow you to specify the width
  115. of the pattern for which MacsBug searches. One of these options
  116. allows MacsBug to look for 24 bit pointers.
  117.  
  118. The heap dump display is more detailed and works with 24 bit
  119. and 32 bit heaps.
  120.  
  121. An extension to the GT command allows you to specify
  122. one or more MacsBug commands to be executed
  123. once the specified breakpoint is reached.
  124.  
  125. Beginning with MacsBug 6.1 (but not documented),
  126. the DebugStr trap was extended so that you could include
  127. one or more commands in the message string to DebugStr.
  128. After MacsBug is invoked by the DebugStr trap, in addition
  129. to displaying a message specified with DebugStr, MacsBug
  130. executes the command(s) included in the message for DebugStr.
  131. The syntax for the call is as follows:
  132.  
  133. DebugStr ("string [; cmd]")
  134.   string is the message to display.
  135.   cmd is a MacsBug command or macro.
  136.  
  137. Example:
  138.  
  139. DebugStr ("Checking the heap ;hc ;g")
  140.  
  141. This routine invokes MacsBug, display the message "Checking
  142. the Heap", does a heap check, and resumes execution of the
  143. program.
  144.  
  145. The printf dcmd included in “Debugger Prefs” allows you to
  146. produce formatted output.
  147.  
  148. =================================================
  149.  
  150. Changes after the 6.2 release notes went final
  151.  
  152. The 'mxbh' help resource now resides in the “MacsBug” file
  153. of MacsBug 6.2.
  154.  
  155. SC6, SC7, and HZ take optional parameters. More information on
  156. these parameters can be obtained from the help command.
  157.  
  158. The SC commands allow to crawl stacks anywhere in the memory.
  159. HZ knows about embedded, 24 bit, and 32 bit heaps.
  160. HX allows to switch to partially damaged heaps.
  161. HD knows a new Q option and displays an additional summary line.
  162.  
  163. HZ and HD display partially damaged blocks and heaps with ! or ?
  164. next to the address.
  165.  
  166. If an address is in a known resource but not in a known
  167. procedure then an artificial symbol may be displayed by MacsBug.
  168. E.g. 'CODE 0006 0C20 Pickers'+0262 indicates the address which
  169. is $262 bytes offset into CODE 6 resource, named "Pickers", of
  170. file $0C20.
  171.  
  172. =================================================
  173.  
  174. We know about some bugs :
  175.  
  176. If ATR is on and A0 points into hardware registers on some
  177. NuBus cards then reading the bytes which A0 points to may
  178. cause the card to perform erratically (e.g. video flickering,
  179. network malfunction).
  180. For now try to use ATT instead in such situations.
  181.  
  182. Sometimes MacsBug loses FPU status when an NMI interrupts
  183. two consecutive FPU instructions.
  184. If you encounter this use _DebugStr instead of hitting the NMI.
  185.  
  186. There are still problems with a few video cards and video
  187. drivers.
  188. For now if you have more than one screen try to run MacsBug
  189. on the other screen.
  190.  
  191. If you use a pre-release of System 7.0 and switch VM on then
  192. use common sense to avoid :
  193. - using the MacsBug Find command over NuBus card memory
  194. - searching for symbols in memory that is swapped to disk
  195.   (you may want to consider using the SX command)
  196.  
  197. ATHC sometimes reports an invalid heap if the Memory Manager
  198. calls _BlockMove while the heap zone free bytes are not yet
  199. adjusted.
  200. For now ignore these warnings or use ATHCA.
  201.  
  202. The source code provided for dcmds requires MPW 3.1 to build
  203. the dcmds. It currently does not build with MPW 3.2.
  204. This does not affect the execution of the dcmds included in
  205. the file “Debugger Prefs”.
  206.  
  207. =================================================
  208.  
  209. In addition to these specific changes,
  210. you should find MacsBug 6.2 easier to use.
  211.  
  212. Whenever possible its output has been made more articulate
  213. and its displays more intelligible.
  214.  
  215. Feedback is an important and appreciated contribution.
  216.